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EVAL  SYSTEM  SPECIFICATION 


1.0  INTRODUCTION 


1.1  Purpose  of  the  System  Specification 

The  EVAL  System  Specification  is  a  technical  document 
written  for  software  development  personnel.  Together  with 
the  EVAL  Functional  Description,  it  guides  the  software 
development  effort  by  identifying  the  functional  requirements 
and  by  providing  structured  logic  diagrams  that  depict  the 
flow,  control,  and  processing  of  information  within  the 
system. 

The  System  Specification  is  generic  and  is  intended  to 
guide  and  facilitate  the  preparation  of  the  language-specific 
and  computer  hardware-specific  documentation  and  coding  that 
are  necessary  to  implement  and  operate  EVAL  at  an  installation. 

1.2  References 

1.2.1  IBM,  HIP0-- A  Design  Aid  and  Documentation  Tech¬ 
nique.  Technical  Publication  GC20-1851-0. 

White  Plains,  New  York:  IBM,  October  1974.- 

1.2.2  Allardyce,  Linda  B. ;  Amey ,  Dorothy  M. ;  Feuer- 
werger,  Phillip  H.;  Gulick,  Roy  M.  Documentation 
of  Decision-Aiding  Software:  EVAL  Functional 
Description .  McLean,  Virginia:  Decisions  and 
Designs,  Incorporated,  November  1979. 

1.2.3  Allardyce,  Linda  B. j  Amey,  Dorothy  M. ;  Feuer- 
werger,  Phillip  H. t  Gulick,  Roy  M.  Documentation 
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of  Decision-Aiding  Software:  EVAL  Users  Manual. 
McLean,  Virginia:  Decisions  and  Designs,  Incor¬ 
porated,  November  1979. 


1.3  Terms 

1.3.1  EVAL  -  EVAL  is  an  abbreviation  for  evaluation, 
reflecting  the  system's  major  area  of  applicability. 

1.3.2  HIPO  -  The  specification  uses  the  standard  Hier¬ 
archy  plus  Input- Process-Output  (HIPO)  diagramming  technique 
to  depict  the  structural  design  and  logical  flow  of  the 
system.  A  legend  explaining  the  HIPO  diagramming  symbols  is 
included.  Reference  1.2.1  provides  a  complete  description 
of  the  HIPO  documentation  technique. 


2.0  DESIGN  DETAILS 


2.1  Background 

Systems  development  personnel  should  refer  to  the  EVAL 
Functional  Description#  Reference  1.2.2,  in  conjunction  with 
the  documentation  contained  in  this  specification.  The 
Functional  Description  details  the  evaluation  models  imple 
mented  by  EVAL  and  discusses  the  specific  functions  that  the 
software  must  perform.  In  addition,  systems  development 
personnel  may  wish  to  refer  to  the  EVAL  User's  Manual, 
Reference  1.2.3. 

2.2  General  Operating  Procedures 

EVAL  is  a  menu-driven  system.  That  is,  the  system  is 
designed  to  interact  with  the  user  by  presenting  a  sequen¬ 
tial  hierarchy  of  menus  and  asking  the  user  to  respond  by 
selecting  one  option  from  the  current  menu.  If  the  user 
does  not  select  one  of  the  menu  options,  the  system  displays 
the  previous  menu.  In  this  manner,  the  user  moves  up  and 
down  the  hierarchy,  as  desired.  Whenever  data  entry  is 
required  as  a  result  of  option  selection,  the  system  speci- 

r 

fically  requests  the  data  and  specifies  the  format. 

The  system  is  also  designed  to  be  generally  forgiving 
of  procedural  errors  by  the  user. 

2.3  System  Logical  Flow 

EVAL  is  a  hierarchically  structured,  modular  software 
system.  The  system  structure  and  logical  flow  lends  itself 
to  presentation  in  the  form  of  HIPO  diagrams,  which  are 
contained  in  this  document. 
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The  main  purpose  of  the  HIPO  diagrams  is  to  provide,  in 
a  pictorial  manner,  the  complete  set  of  modular  elements 
necessary  to  the  operation  of  EVAL,  including  all  input, 
output,  and  internal  functional  processing.  This  is  done  by 
displaying  the  input  items  necessary  to  the  process  step 
which  uses  them,  defining  the  process,  and  showing  the 
resulting  output  of  the  process  step. 

The  HIPO  documentation  diagrams  are  designed  and  drawn 
in  a  hierarchical  fashion  from  the  main  calling  routines  to 
the  detail-level  operation/calculation  routines.  Extended 
written  descriptions  are  given  below  a  HIPO  diagram  whenever 
it  is  deemed  necessary. 

A  complete  description  and  explanation  of  the  symbolic 
notation  used  in  the  HIPO  diagrams  is  given  in  Reference 
1.2.1.  An  abbreviated  legend  for  the  symbols  used  in  this 
specification  is  given  in  Figure  2-1.  Note  that: 

a.  External  subroutines  are  depicted  partly  in  the 
Process  block  and  partly  out.  Internal  subroutines 
are  always  shown  within  the  Process  block. 

b.  Overview  diagrams  show  general  inputs  and  outputs 
only,  whereas  detail/subroutine-level  diagrams 
show  specific  input/output  tables  and/or  displays. 

c.  Rectangular  boxes  inside  the  Input/Output  block 
areas  are  generally  used  to  denote  single  data 
items.  Two  or  more  boxes  are  grouped  to  show  that 
several  data  items  are  input/output. 

d.  Rectangular  boxes  inside  the  Process  block  indi¬ 
cate  repetitive  subprocesses. 
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Data  reference 
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DISPLAY 


Keyed  data  arrows 
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of  functions 


Function  identified 
|  but  not  included  in 
•  package 


General  flow  of  data 
among  subprocesses 

Subroutine  invoked 
(Return  is  made  to 
calling  routine) 

Routine  receives  control 

Routine  exits 
or  returns  control 


Information  display  by 
online  indicators  -  prompted 
by  program  execution  or  by 
keyboard  input,  especially  CRT 


ONLINE 

STORAGE 


Any  general 
input  or  output  item 


Input/output  medium  - 
includes  drum,  disk,  tape, 
diskettes 


[magnetic]  Magnetic  tape 
I  TAPE  j  input/output  medium 


Figure  2-1 
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The  HIPO  diagrams  appear  in  the  next  section,  which 
completes  the  system  specification. 

2.4  HIPO  Documentation 

The  HIPO  diagram  identification  numbers  and  figure 
numbers  used  in  this  section  stand  alone;  i.e.,  they  start 
with  1.0,  increase  hierarchically,  and  are  independent  of 
the  numbering  scheme  used  to  this  point  in  this  document. 

The  EVAL  software  consists  of  two  separate  subsystems: 
STRUCTURE  and  RUN.  Figure  2-2  is  the  system  overview  chart. 
The  STRUCTURE  subsystem  is  used  to  create  a  new  evaluation 
structure  or  to  revise  an  existing  structure.  The  RUN 
subsystem  is  used  to  specify  importance  weights  and  utilities 
and  to  display  the  results  of  an  evaluation  model. 

Figure  2-3  is  a  subsystem  structure  chart  for  the 
STRUCTURE  .subsystem.  It  represents  the  overall  program 
logic  flow  in  a  visual  table  of  contents.  The  Visual  Table 
of  Contents  diagram  shows  the  hierarchical  structure,  the 
functional  description  labels,  and  the  diagram  (chart) 
identifiers  of  the  functions  performed  by  STRUCTURE. 
Similarly,  Figure  2-4  is  a  visual  table  of  contents  diagram 
for  the  RUN  subsystem. 


EVAL 


STRUCTURE 

■ 

RUN 

SUBSYSTEM 

SUBSYSTEM 

Figure  2-3 

Figure  24 

Figure  2-2 

EVAL  SYSTEM  OVERVIEW 
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STRUCTURE 


Figure  2-3 

STRUCTURE  VISUAL  TABLE  OF  CONTENTS 


VISUAL  TABLE  OF  CONTENTS 


Extended  Description 

8.  Groups  of  nodes  may  be  deleted  from  the  currently  defined  structure. 

9.  A  printout  of  the  structure  as  it  is  currently  defined  is  obtained. 

10.  The  program  ends  here:  a  restart  option  will  cause  step  1  to  be  executed  ai 
When  a  session  is  terminated,  all  branch  structures  or  subtrees  defined  are  deleti 


System /Program:  STRUCTURE _  Name: 

Diagram  ID:  -12 - Description — Load_A_Mgjel 


1.  The  user  may  have  many  tape  files  on  which  formatted  models  are  stored.  4.  The  user  is  prompted  for  a  model  selection:  the  response  may  be  the  list  item 

In  this  step,  the  user  is  prompted  for  a  response  indicating  the  desired  tape  is  number  or  the  model  name.  The  requested  model  is  stored  in  the  same  tape  file  as 

mounted  and  online.  its  position  relative  to  the  other  model  names  in  the  displayed  list. 

3.  The  names  of  the  models  existing  on  the  mounted  tape  are  displayed  in  list  or 
MENU  format  so  that  the  user  may  select  a  model  for  loading. 


Name:  LOAD  VARS 


PROCESS 


Description  Edit  th»  S 


System /Program  STRUCTURE _  Name:  LOCATE 

Diagram  ID;  -3 d _ Determine  the  Node  Location 


Extended  Description 

S.  The  existing  outline  table  is  searched  for  a  matching  encoded  outline  number.  It 
is  the  index  into  this  table  of  the  matching  outline  number  which  is  returned  to  the 
calling  routine  in  step  6. 


System  Program:  STRUCTURE _  Name:  _ 

Diagram  ID:  JL2 - EDIT  •  Delate  or  Rename 


System  Program:  STRUCTURE _  Name:  SPLIT _ 

Diagram  ID:  3~2'1 _ Description  lnvest*9ate  and  Split  Node  Identifiers 


System  Program:  STRUCTURE _  Name:  _ 

Diagram  ID:  Mi? -  Description  Pe*ete  a  Node -  Page: 


System.'Program:  STRUCTURE _  Name:  ADDNOOES _ _ 

Diagram  10:  — U -  Description — Nodes  to  a  Structure _  Page: 


2  •  3.  Additions  to  previously  initialized  or  existing  variables  are  accomplished  by 
extending  the  arrays  such  that  the  corresponding  orders  of  associated  labels, 
scores,  types,  weights  and  decoded  outline  numbers  are  the  same. 


System  .'Program.  STRUCTURE _  Name:  _ 

Diagram  ID:  -A2 _ Description -iOlgLjJjggLSlmcture _  p^e 


4.  The  user  is  prompted  for  input  which  will  be  used  to  define  a  hierarchical  tree 
structure  described  by  outline  numbers,  labels  and  types  of  nodes  within  the 


System  Program:  STRUCTURE _  Name  _ 

Diagram  ID  _  Descnpt.on  _DeveloP  the  Structure _  p.,qe 
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2.b.  If  the  nodes'  associated  data  mask  element  indicates  an  aggregate  node,  th« 
the  contributing  nodes  are  all  the  nodes  which  follow  in  sequential  order  that  hi 
an  associated  LEVELS  number  that  is  less  than  the  selected  nodes  LEVELS 
numbers,  provided  these  nodes  occur  before  any  node  with  equal  or  higher 
LEVELS  number. 


Program:  STRUCTURE _  Name:  _ 

ID:  JSL _ Description  A”***  Current  Model 


4.  The  existing  file  structure  and  the  amount  of  available  space  on  the  data  tape 
are  checked  along  with  the  user  specification  to  determine  where  the  model 
variables  are  to  be  stored. 


6.  The  library  name  list  is  updated  to  include  the  new  file.  The  new  model  name's 
position  in  the  UBNAMES  array  must  be  the  same  relative  position  to  other 
models  stored  on  the  device. 


'Program :  STRUCTURE _  Name:  FH-ELOC 

1 1D  _§J _ Description  Fi«*  Filc  Location _ 


STRUCTURE _  Name:  PUMPVARS _ 

Diagram  ID:  -&2 - Description  Save  the  Model  Variables  _  .  —  —  _ _  Page: 


System. Program :  STRUCTURE _  Name:  SAVELIB _ 

Diagram  ID:  -§i3 -  Description _ Save  the  Library _  Page: 


Return 


System/Program  STRUCTURE _  Name:  _ 

Diagram  ID  _L2 _ n...-  Create  a  Branch  to  the  Structure 


Extended  Description 

The  user  is  allowed  to  create  separate  branch  or  subtree  structures  which  may  be 
added  to  the  model  structure  under  the  "create  a  structure"  process  option. 


System 'Program  STRUCTURE _  _  Name:  _ 

D.agram  ID:  _L! _ Pescnpt.on  Cfeate  aNon-Symmetric  Branch _  Pdge. 


System/Program:  STRUCTURE _  Name  _ 

Diagram  ID  _L2 _ rw,r.,„„  Create  a  Symmetric  Branch 


Step  2  processing  ensures  that  for  each  subsequent  level  of  a  multilevel  branch 
structure  the  outline  number,  types  and  labels  are  all  added  in  the  correct  numerical 
sequence  to  the  outline,  types  and  label  entries  at  the  previous  level.  (This  is 
done  for  every  branch  node  defined  at  the  previous  level.) 


System/Program  STRUCTURE _  _  Name:  _ 

Diagram  ID:  9.0 -  Description _ Print  a  Review  Sheet  Page: 


Extended  Description 

2.  The  decoded  outline  identifier  number  is  formatted  for  output.  The  output 
should  be  equivalent  to  the  user's  original  input  during  the  creation  of  the  structure. 


System /Proyam:  STRUCTURE _  Name:  _ 

Diagram  ID:  J&3 _ Select  Only  Numeric  Input 


This  routine  will  not  be  required  if  system  error  checking  routines  interface 
with  the  standard  keyboard-display  input. 


System/Program  Sjj! _  Name:  WUN 

Diagram  ID:  -Lfi _ Description  Entrance  to  Eval  Program 


Extended  Description 

3.  The  model  variables  are  all  loaded  into  the  current  work  area  at  this 
time,  or  whenever  the  user  wishes  to  load  a  new  model.  Consequently, 
this  documentation  assumes  that  these  variables  are  "global"  and 
always  available  for  reference,  input  to  procedures,  or  modification. 


Display/Edit 


c.  This  generates  a  node  outline  number  one  level  higher  than  the 
previously  processed  node.  For  example,  if  the  previously  processed 
number  were  3.2.5  and  the  input  '0)*  I  where  the  right  parenthesis  is 
the  scan  operator),  the  new  node  outline  number  would  be  3.2. 


INPUT  PROCESS  OUTPUT 


PROCESS 


Systtm/Progt am :  _ _  Name:  DISP 

Oiagram  ID:  -5L2 - n«trt.pt.nn  Display  Group _ 


System/Program:  RUN _  Name:  TRACE _ 

Diagram  ID:  -2.JL1 _ Descnpt.on  Get  Nodes  of  Thread  UP  Tree 


For  instance,  if  the  requested  node  number  is  1 .4.2.6,  the  next 
higher  level  would  be  1.4.2,  and  the  fourth  (or  highest)  calculated 


System/Program:  _  Name:  EDITLINE 

Diagram  10:  -2JJ _ Edit  a  Numeric  Vector _ 


System /Program : _ BUN _ _  Name:  GETRANGE _ _ 

DMiran  10:  _2J _ n _ p. _ Elicit  Ranges  for  Computing  Sensitivity  Analysis 


System /Program 


Extended  Description 

2.  When  the  cum.  weight  of  the  specified  node  is  altered,  the  total  of  the 
cum.  weights  of  all  other  nodes  automatically  goes  up  or  down  such 
that  the  sum  remains  the  same.  The  model  variable  containing  the  cum. 
weights  does  not  have  to  be  changed  from  its  original  set  of  values. 
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Return 


SyiMffl/Pro9rMn:  RUN _  Name:  ROLLBACK _ 

Diagram  10:  -ij _ Description .  Calculate  Model _ _  page: 


System  /Program:  “V™ - Name:  ffl _ 

Diagram  10:  -1.2,3 _ Description  CatculateType  W _  page: 


System/Program:  RUN _  Name:  CUMWT _ 

D.agram  10:  * _ Oescr.pt, on  _Ca<Cutate  Cumulativg  Weight _  page: 


Syjtem/Program:  RUN _ _  Name:  SHOWALL 

Diagram  ID:  .  _ n»t<-r.p>.^.r.  Print  Results _ 


ujRiey 


PROCESS 


System/Program:  BUM _  Name:  LOADDRIVE 

Diagram  10:  -&Q _ Qescr.pt, on  load  Model  From  Tapes _ 


INPUT _  PROCESS  OUTPUT 


Extended  Description 

Position  of  model  names  within  list  indicates  where  models  are 
stored  on  tape. 


Sysitffl/Progiam:  _  Name:  LOAD _ 

Diagram  ID:  §-„,: _ Description  Load  Model  Variables _  Page: 


System/Program:  _RUN _  Name:  LOAD _ _ _ 

Diagram  ID:  . fi^ - Description  Load  Model  Variables  Page: 


System/Program:  BUM _  Name:  SAVEDRIVE _ 

Diagram  ID:  -2 ifi - Description -  Page: 


System  /Program:  RUN _  Name:  SAVEDRIVE _ 

Otagram  ID:  JLQ - Description -  Page: 


76 


INPUT  PROCESS  OUTPUT 


_  Name:  SAVE _ 

Save  Model  Variables  on  Ta 


« 
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System/Program:  RUN _  Name:  SAVLIB _ 

Diagram  ID:  ^-3 - Description — Save  List  of  Model  Names - - -  Page: 


Return 


System/Program:  _  Name:  DATASHEET _ 

Diagram  ID:  9  Q - Description _ Print  Data  Sheet _ _ — - - - - - -  Page: 


System /Program :  Name:  NUMBERSONLV _ 

Diagram  ID:  10-3 _ Description  Convert  Character  Numbers  to  Numeric 


System/Program:  _  Name:  VESNO _ 

Diagram  ID:  1?-^ - Description— — - - - - - - - - - - Page: 


